#ifndef FILE_ITERATOR_H
#define FILE_ITERATOR_H

#include <stddef.h>
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    FILE_TYPE_ALL = 0,    // All files
    FILE_TYPE_AUDIO,      // .mp3, .wav, .aac, .flac, .ogg
    FILE_TYPE_VIDEO,      // .mp4, .avi, .mkv, .mov 
    FILE_TYPE_IMAGE,      // .jpg, .jpeg, .png, .bmp, .gif
    FILE_TYPE_CUSTOM      // Custom extensions
} file_type_t;

typedef struct  {
    size_t count;
    size_t index;
    char **list;
    const char *directory_path;
} file_iterator_instance_t;

/**
 * @brief 根据文件类型创建迭代器
 * 
 * @param base_path 要搜索的目录路径
 * @param type 文件类型
 * @param custom_exts 自定义文件扩展名，以逗号分隔
 */
file_iterator_instance_t* file_iterator_new(
    const char *base_path,
    file_type_t type,
    const char *custom_exts);

/**
 * @brief 删除迭代器实例
 *
 * @param i 实例指针
 */
void file_iterator_delete(file_iterator_instance_t *i);

/**
 * @brief 将迭代器移动到下一个条目
 *
 * @return
 *    - ESP_OK: 成功
 *    - Others: 失败
 */
esp_err_t file_iterator_next(file_iterator_instance_t* i);

/**
 * @brief 将迭代器移动到上一个条目
 *
 * @return
 *    - ESP_OK: 成功
 *    - Others: 失败
 */
esp_err_t file_iterator_prev(file_iterator_instance_t* i);

/**
 * @brief 获取迭代器中的项目数量
 *
 * @return size_t 迭代器中的项目数量
 */
size_t file_iterator_get_count(file_iterator_instance_t* i);

/**
 * @brief 获取当前迭代器的索引
 *
 * @return 当前迭代器的索引
 */
size_t file_iterator_get_index(file_iterator_instance_t* i);

/**
 * @brief 设置迭代器索引，如果索引无效则设置为0
 *
 * @param index 要设置的索引值
 */
void file_iterator_set_index(file_iterator_instance_t* i, size_t index);

/**
 * @brief 获取指定索引对应的文件名
 *
 * @param index 文件条目索引(参见file_iterator_get_index())
 * @return 指定索引对应的文件名，如果不存在则返回NULL
 */
const char *file_iterator_get_name_from_index(file_iterator_instance_t* i, size_t index);

/**
 * @brief 获取指定索引对应的完整文件路径
 *
 * @param path 指向长度为path_len的缓冲区的指针
 * @return 实际存储到path中的字符数，或者如果缓冲区足够大时将会存储的字符数，
 *         如果索引无效则返回0
 */
int file_iterator_get_full_path_from_index(file_iterator_instance_t* i, size_t index, char* path, size_t path_len);

#ifdef __cplusplus
}
#endif

#endif /* FILE_ITERATOR_H */